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Link Relation Types for Web Services 
Abstract 


Many resources provided on the Web are part of sets of resources that 
are provided in a context that is managed by one particular service 
provider. Often, these sets of resources are referred to as "Web 
services" or "Web APIs". This specification defines link relations 
that represent relationships from Web services or APIs to resources 
that provide documentation, descriptions, metadata, or status 
information for these resources. Documentation is primarily intended 
for human consumers, whereas descriptions are primarily intended for 
automated consumers. Metadata provides information about a service’s 
context. This specification also defines a link relation to identify 
status resources that are used to represent information about service 
status. 


Status of This Memo 


This document is not an Internet Standards Track specification; it is 
published for informational purposes. 


This document is a product of the Internet Engineering Task Force 


(IETF). It represents the consensus of the IETF community. It has 
received public review and has been approved for publication by the 
Internet Engineering Steering Group (IESG). Not all documents 


approved by the IESG are candidates for any level of Internet 
Standard; see Section 2 of RFC 7841. 


Information about the current status of this document, any errata, 


and how to provide feedback on it may be obtained at 
https://www.rfc-editor.org/info/rfc8631. 
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1. Introduction 


One of the defining aspects of the Web is that it is possible to 
interact with Web resources without any prior knowledge of the 
specifics of the resource. Following the practices described in Web 
architecture [W3C.REC-webarch-20041215] by using URIs, HTTP, and 
media types, the Web’s uniform interface allows interactions with 
resources without the more complex binding procedures often necessary 
with other approaches. 


Many resources on the Web are provided as part of a set of resources 
that are referred to as a "Web service" or a "Web API". In many 
cases, these services or APIs are defined and managed as a whole, and 
it may be desirable for clients to be able to discover this service 
information. 


Service information that provides information on how to use service 
resources can be broadly separated into two categories: One category 
primarily targets human users and often uses generic representations 
for human readable documents, such as HTML or PDF. The other 
category is structured information that follows a more formalized 
description model and is primarily intended for consumption by 
machines -- for example, tools and code libraries. 


In the context of this memo, the human-oriented variant is referred 
to as "documentation", and the machine-oriented variant is referred 
to as "description". 


These two categories are not necessarily mutually exclusive, as 
representations have been proposed that are intended for both human 
consumption and interpretation by machine clients. In addition, a 
typical pattern for service documentation/descriptions is that there 
is human-oriented, high-level documentation that is intended to put a 
service in context and explain the general model, which is 
complemented by machine-level descriptions that are intended as 
detailed technical descriptions of the service. These two resources 
could be interlinked, but since they are intended for different 
audiences, it can make sense to provide entry points for both of 
them. 


In addition, while both documentation and descriptions may be 
provided as part of a Web service, there may be other information as 
well. Generally speaking, a Web service may have any metadata/ 
resources associated with it (with documentation and descriptions 
being two specific kinds of resources). If there is a way in which 
all of these metadata/resources can be represented, then it should be 
possible to find such a resource that provides access to general Web 
service metadata. 
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In addition to these resources about mostly static aspects of a Web 
service, this memo also defines a link relation that allows providers 
of a Web service to link to a resource that represents status 
information about the service. This information often represents 
operational information that allows service consumers to retrieve 
information about "service health" and related issues. 


This memo places no constraints on the specific representations used 


for all of these resources. It simply allows providers of a Web 
service to make the documentation, descriptions, metadata, and status 
of their services discoverable and defines link relations that serve 


that purpose. 


2. Terminology 
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 
"SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 


"OPTIONAL" in this document are to be interpreted as described in 
BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all 
capitals, as shown here. 


3. Web Services 


"Web Services" or "Web APIs" (sometimes also referred to as "HTTP 
API" or "REST API") expose information and services on the Web. 
Following the principles of Web architecture 
[W3C.REC-webarch-20041215], they expose URI-identified resources, 
which are then accessed and transferred using a specific 
representation. Many services use representations that contain 
links, and these links are often typed links. 


Using typed links, resources can identify relationship types to other 
resources. RFC 8288 [RFC8288] establishes a framework of registered 
link relation types, which are identified by simple strings and 
registered in an IANA registry. Any resource that supports typed 
links according to RFC 8288 can then use these identifiers to 
represent resource relationships on the Web without having to 
reinvent registered relation types. 


In recent years, Web services, as well as their documentation and 
description languages, have gained popularity due to the general 
popularity of the Web as a platform for providing information and 
services. However, the design of documentation and description 
languages varies according to a number of factors, such as the 
general application domain, the preferred application data model, and 
the preferred approach for exposing services. 
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This specification allows service providers to use a unified method 
to link to service documentation and/or descriptions. This link 
should not make any assumptions about the provided type of 
documentation and/or descriptions, so service providers can choose 
those that best fit their services and needs. 


This specification also allows service providers to link to general 
service metadata. One part of the metadata may have links to 
documentation and/or description as well as other information about a 
service, such as deployment or operational information. 


3.1. Documenting Web Services 


In the context of this specification, "documentation" refers to 
information that is primarily intended for human consumption. 
Typical representations of this kind of documentation are HTML and 
PDE . 


Documentation is often structured, but its structure depends on the 
structure of the service in question as well as the specific way in 
which the authors choose to present it. 


3.2. Describing Web Services 


In the context of this specification, "description" refers to 
information that is primarily intended for machine consumption. 
Typical representations are dictated by the technology underlying the 
service itself, which means that description formats in today’s 
technology landscape are based on XML, JSON, Resource Description 
Framework (RDF), and a variety of other structured data models. In 
each of those technologies, there may be a variety of languages 
defined to serve the same general purpose of describing a Web 
service. 


Descriptions are always structured, but the structuring principles 
depend on the nature of the described service. For example, one of 
th arlier service description approaches, the Web Services 
Description Language (WSDL), uses "operations" as its core concept, 
which are essentially identical to function calls because the 
underlying model is based on the Remote Procedure Call (RPC) model. 
Other description languages for non-RPC approaches to services will 
use different structuring approaches, such as structuring service 
descriptions by URIs and/or URI patterns. 
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3.3. Unified Documentation/Description 


If service providers use an approach where there is no distinction 
between service documentation (Section 3.1) and service description 
(Section 3.2), then they may not feel the need to use two separate 
links. In such a case, an alternative approach is to use the 
previously defined "service" link relation type [RFC5023], which does 
not indicate whether it links to documentation or description and 
thus may be a better fit if no such differentiation is required. 


4. Link Relations for Web Services 


In order to allow Web services to represent the relation of 
individual resources to service documentation/description and 
metadata, this specification introduces and registers three new link 
relation types. 


4.1. The service-doc Link Relation Type 


The "service-doc" link relation type is used to represent the fact 
that a resource or a set of resources is documented at a specific 
URI. The target resource is expected to provide documentation that 
is primarily intended for human consumption. 


4.2. The service-desc Link Relation Type 


The "service-desc" link relation type is used to represent the fact 
that a resource or a set of resources is described at a specific URI. 
The target resource is expected to provide a service description that 
is primarily intended for machine consumption. In many cases, it is 
provided in a representation that is consumed by tools, code 
libraries, or similar components. 


4.3. The service-meta Link Relation Type 
The "service-meta" link relation type is used to link to available 
metadata for the service context of a resource. Service metadata is 
any kind of data that may be of interest to existing or potential 


service users, with documentation/description being only two possible 
facets of service metadata. The target resource is expected to 
provide a representation that is primarily intended for machine 
consumption. In many cases, it is provided in a representation that 
is consumed by tools, code libraries, or similar components. 


Since service metadata can have many different purposes and use many 
different representations, it may make sense for representations 
using the "service-meta" link relation to offer additional hints 
about the specific kind or format of metadata that is being linked. 
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This definition of the "service-meta" link relation makes no specific 
assumptions about how these link hints will be represented, and the 
specific mechanism will depend on the context where the "service- 
meta" link relation is being used. 


One example is that a "service-desc" link may identify an OpenAPI 
description, which is supposed to be the machine-readable description 
of a Web API. A "“"service-meta" link may identify a resource that 
contains additional metadata about the Web API, such as labels that 
classify the API according to a labeling scheme and a privacy policy 
that makes statements about how the Web API manages personally 
identifiable information. 


5. Web Service Status Resources 


Web services providing access to one or more resources often ar 
hosted and operated in an environment for which status information 
may be available. This information may be as simple as confirming 
that a service is operational, or it may provide additional 
information about different aspects of a service and/or a history of 
status information, possibly listing incidents and their resolution. 


The "status" link relation type can be used to link to such a status 
resource, allowing service consumers to retrieve information about a 
Web service’s status. Such a link may not be available for and from 
all resources provided by a Web service -- only from key resources 
such as a Web service’s metadata resource and/or a service’s home 
resource (i.e., a resource analogous to the home page of a Web site). 


This memo does not restrict the representation of a status resource 
in any way. It may be primarily focused on human or machine 
consumption or a combination of both. It may be a simple "traffic 
light" indicator for service health or a more sophisticated 
representation conveying more detailed information, such as service 
subsystems and/or a status history. 
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6. IANA Considerations 


The link relation types below have been registered by IANA per 
Section 4.2 of RFC 8288 [RFC8288]. 


6.1. Link Relation Type: service-doc 
Relation Name: service-doc 
Description: Identifies service documentation for the context that 


is primarily intended for human consumption. 


Reference: RFC 8631 
6.2. Link Relation Type: service-desc 
Relation Name: service-desc 


Description: Identifies service description for the context that is 
primarily intended for consumption by machines. 


Reference: RFC 8631 


6.3. Link Relation Type: service-meta 


Relation Name: service-meta 


Description: Identifies general metadata for the context that is 
primarily intended for consumption by machines. 


Reference: RFC 8631 


6.4. Link Relation Type: status 


Relation Name: status 
Description: Identifies a resource that represents the context’s 
status. 


Reference: RFC 8631 
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7. Security Considerations 


Web service providers should be aware that service descriptions and 
documentation may be used by attackers to gain additional information 
about a service (particularly its implementation) and to test for 
known security issues. It may thus be advisable to restrict service 
descriptions and documentation to aspects of a service that are 
necessary and to exclude any details that are not necessary for using 
the service. 


Another potential security issue for Web service providers is that 
publishing service descriptions and documentation may generally allow 
clients (both malicious and otherwise) more automated and systematic 
access to a service. It may therefore be possible that more of a 
service’s potential vulnerabilities are mad asier to find and 
exploit or simply that a service might receive more load because it 
is accessed by automated clients. 


Web service consumers should be aware that service descriptions and 
documentation can be out of sync or simply incorrect. Blindly 
trusting service descriptions and documentation (particularly when 
descriptions are retrieved and interpreted programmatically) is not a 
safe practice. Web service consumers SHOULD always assume that 
service descriptions and documentation may be incorrect and SHOULD 
therefore be prepared to handle errors at runtime. 
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